MacAPRS™ & WinAPRS™
Documentation

written by
Mark Sproul (KB2ICI)
and Keith Sproul (WU2Z)

The current version of MacAPRS™ is 3.1.0

The current version of WinAPRS™ is 2.1.0

Last updated December 9, 1997

Email the authors at sproul@ap.org or ksproul@rci.rutgers.edu

Quick Start

About this document

This document is created for viewing with a Web Browser AND as printed text. Therefore there are features of this document that may seem slightly redundant. This way, as little is lost as possible when the document is printed. You can download this document and view it with your web browser. The ENTIRE documentation in web format and the images is available as a ZIP file, download it, pkunzip with -d option, then open INDEX.HTM with your favorite web browser. This way you can have the documentation locally and not have to view it on line.

APRSdocs.zip at ftp://aprs.rutgers.edu/pub/hamradio/APRS/APRSdocs.zip

Netscape has an option to add titles and page numbers to web documents when printed, this is very useful if you want to print this.

Preface

MacAPRS™ and WinAPRS™ are very similar. They are actually one set of source code, written in "C/C++" compiled for two different environments. There are some feature differences but nothing major. Our intent is to make both versions as full featured as possible. There are some things on the Mac that are not easily accomplished on the Windows platform that will never get implemented (such as the speech output of messages). In this document, features found in the Mac version will be noted with the Apple Icon and features found in the Windows version will be noted by the Windows Icon.
Mac Version Windows Version

Table of Contents

  1. Overview and Setup

  2. User Reference

  3. Advanced Features

  4. Trouble Shooting etc

  5. Related Documents

  6. Index

INTRODUCTION

WinAPRS™ is a version of MacAPRS™ for the Windows operating system. WinAPRS implements the APRS™ protocol for Automatic Position Reporting System originally developed by Bob Bruninga.

MacAPRS™ and WinAPRS™ are licensed versions of APRS™. "APRS" is trademarked by Bob Bruninga, MacAPRS and WinAPRS are trademarked by Mark and Keith Sproul.

Overview

Bob Bruninga, WB4APR, developed a system for tracking objects using Packet Radio. His system uses unconnected packets (UI frames) for transmitting the position and other information about each station or object. He has been working on this system since 1984. In 1992 Bob presented a paper at the ARRL Computer Networking Conference that introduced the DOS program called APRS (Automatic Position Reporting System). APRS is a program that receives these packets and displays the objects on a map on your computer screen. Since then, APRS has become quite popular in Packet Radio and is gaining new users daily.

MacAPRS / WinAPRS are implementations of WB4APR's APRS protocols. MacAPRS / WinAPRS are written in "C" using none of the code from Bob's original QuickBasic program. MacAPRS / WinAPRS is designed to be fully compatible with the protocols developed by Bob Bruninga.

New Users

The APRS family of software has many uses and is many different things to different people. APRS can be used for There are many little things about APRS that users, both new and and old get caught up on, these include path settings, (WIDE, GATE, etc). The use of gateways (HF to VHF and VHF to HF).

Shareware

MacAPRS and WinAPRS are shareware. The shareware registrations are The downloadable versions of MacAPRS and WinAPRS are fully functional and are the SAME versions that registered users have. The only difference is that if you are not registered, you cannot save your settings. One registration covers ALL aspects, there are no hidden charges or extra charges for extra features. When you register, you will receive a validation number. This number allows you to save your settings.

All payments MUST be in US dollars and checks must be drawn on a US bank. International money orders are also fine.
Please send shareware fees to

Recent additions to MacAPRS and WinAPRS

Down load the latest version from

MacAPRS Version 3.1.0 - Dec 9, 1997
WinAPRS Version 2.1.0

MacAPRS Version 3.0.8 - Nov 19, 1997
WinAPRS Version 2.0.8

MacAPRS Version 3.0.7 - Oct 31, 1997
WinAPRS Version 2.0.7

MacAPRS Version 3.0.6 - Oct 14, 1997
WinAPRS Version 2.0.6

MacAPRS Version 3.0.5 - Sep 21, 1997
WinAPRS Version 2.0.5

WinAPRS Version 2.0.3 - Sep 13, 1997

MacAPRS Version 3.0.2 - Sept 5, 1997
WinAPRS Version 2.0.2

MacAPRS Version 3.0.1 - May 26, 1997
WinAPRS Version 2.0.1

MacAPRS Version 3.0.0 - May 16, 1997 (Dayton hamfest)
WinAPRS Version 2.0.0

MacAPRS Version 2.9.5 - April 25, 1997
WinAPRS Version 1.4.5

MacAPRS Version 2.9.0 - March 27, 1997
WinAPRS Version 1.4.0

MacAPRS Version 2.8.0 - February 15, 1997 (Orlando Hamfest)
WinAPRS Version 1.3.0

MacAPRS Version 2.7.4 - February 1, 1997 (Miami Hamfest)
WinAPRS Version 1.2.4

MacAPRS Version 2.7.3 - January 12, 1997
WinAPRS Version 1.2.3

MacAPRS Version 2.7.2
WinAPRS Version 1.2.2

MacAPRS Version 2.7.1 - January 5, 1997
WinAPRS Version 1.2.1

MacAPRS Version 2.7.0 - January 1, 1997
WinAPRS Version 1.2.0

MacAPRS Version 2.6.8 - December 26, 1996
WinAPRS Version 1.1.9

MacAPRS Version 2.6.7 - November 14, 1996
WinAPRS Version 1.1.7

Version 1.1.6 - October 27, 1996

Version 1.1.5 - October 22, 1996

Version 1.1.4 - Limited release - for testing only

Version 1.1.3 - August 20, 1996

Version 1.1.2 - July 14, 1996

Version 1.1.0 - June 30, 1996

Version 1.0.0 - May 17, 1996

System Requirements for Macintosh

MacAPRS requires System 7.0 or later. A color Mac with 8 or 12 meg is recommended. MacAPRS will run on low end machines such as the MacPlus or PB-100 as long as System 7 is installed.

MacAPRS will utilize multiple monitors if you have more than one monitor attached to your Mac.

System Requirements for Windows

WinAPRS is written to the Win32 API, which means that it works under Windows NT and Windows 95. To run under Windows 3.1, you will need the Win32S library (DLL).

WinAPRS has been tested on a 386 running Windows95 and while slow, worked just fine. A 486 of at least 33MHz and 8 meg of Ram running either Windows95 or WindowsNT is recommended.

Comm Ports 1 through 8 have been tested and all work fine.

All of my initial testing was on a 486/66 running Windows NT. As of Jan 1, 1996 I am also running on a Pentium/100 running Windows95. (Comment about Windows 95: WinAPRS on the 486 running WindowsNT seems FASTER than on the Pentium running Win95. Also Windows NT is much more stable).

Refer to our Win32S documentation for installation instructions:

OS/2 - OS/2 has a version of Win32S, it is version 1.2.5, at present WinAPRS is NOT compatible with version 1.2.5 of Win32S that is available for OS/2. The compatibility is being investigated and MIGHT be implemented in the future. At present there is no promise to make WinAPRS work with OS/2 but it might happen.

Special note to long-time users of DOS-APRS: WinAPRS is a proper Windows application, it does NOT conform to the menu keys that were implemented under DOS-APRS. Those are a "DOS" implementation. WinAPRS follows official "Windows" programming guidelines. Later on, better short-cut keys, including function keys will be implemented for those features that need it.

INSTALLATION

WinAPRS is normally distributed via the internet as a ZIP file, To unzip the file The "-d" option should make it create the necessary directories and sub-directories.

The ZIP file should unzip to exactly what is below, if it does not, follow these steps.

  1. Create a folder (directory) called "WinAPRS" (or what ever you want)
  2. Copy the following to that folder
  3. Either copy or create a folder called "MAPS". This folder MUST be here and must be called exactly "MAPS".
  4. Put any and all of your maps in the MAPS folder.

  5. Create a folder called "TNCfiles"
  6. Copy all of the TNC settings files into it

    Recommended but not required

  7. Create a folder called DOCS (see section on Help Window)
  8. Copy WAPRSdoc.htm into it

    Optional

  9. Create a folder called "DATA"
  10. Copy AIRPORT.DAT into this folder
  11. Copy ZIPCODE.DAT into this folder

  12. Create a folder called "LABELS"
  13. Copy label files into this folder (see section on global labels)

  14. Create a folder called "OVERLAYS"
  15. Copy any ".POS" files into this folder
Installation diagnostics: On startup, MacAPRS / WinAPRS checks to see if required files are present and if optional files are in the wrong place, any errors are reported. I added this after several problems from users getting things set up correctly. MacAPRS and WinAPRS are growing and expanding, the options and setup procedure are going to get more involved, I will continue to add as much intelligence into the program to assist users as I can.

NOTE IF YOU ARE RUNNING Windows 3.1

CONFIGURATION

Originally I thought that the settings for WinAPRS would have to be dramatically different from what was done for MacAPRS, this is due to the vastly different implementation of dialogs for Windows versus the MacOS. I was able to write software that read the Mac dialog resources and output Windows dialog resource descriptions. This made the conversion dramatically easier and made the dialog boxes for both versions practically identical.

Under the SETTINGS menu there are several different settings dialog boxes. They may not be in this order.

Performance issues

MacAPRS and WinAPRS are multi-faceted programs, they have many uses for many different purposes and people. They can utilize large amounts of system resources. For example, if the ZIPCODE.DAT file is present in the DATA folder, it ALWAYS gets loaded into memory and kept in memory the entire time the program is running. If the file is NOT present, then it is not loaded and the memory is not used. If you are trying to run on smaller systems such as laptops some of these options should be removed. Please keep this in mind when configuring your setup.

APRS Frequencies

APRS is used primarily on these frequencies

TNC Settings

These tips may help in setting up your TNC

The following TNCs have been thoroughly tested with MacAPRS and WinAPRS

Additional TNC settings STARTUP and SHUTDOWN

MacAPRS / WinAPRS will additionally transmit a text file to the TNC on startup and shutdown. These files can contain any TNC commands that you may need and may be of any length. Lines starting with "*" or "!" are comments and not passed to the TNC.

Since you can have more than one TNC in use, Mac/WinAPRS looks for several file names, the first one it finds in each catogory is the one used. Once it finds one of them, it does not look for any of the remaining names. These are determined at STARTUP of the program, to see which file is currently being used, refer to the Internal State Window. The files used for dosAPRS will work just fine for WinAPRS and MacAPRS.

TNC Selection

Under the SETTINGS Menu is "TNC Selection", this displays a list of all of the TNC setup files in the directory "TNCfiles", these files are supplied as standard TNC set up files as described above for each of several different brand and model of TNCs. Select the mode and TNC model that you will be using.

Please note: the settings contained in each of these TNC files may not be perfect for your station but are an attempt to make initial setup easier and quicker.

TNC Commands Menu

Under the SETTINGS menu, there is a sub menu called TNC COMMANDS, under this there are several commands to send APRS strings and affect the TNC.

Help Window

At any time in the program you can press the F-1 key and get the help window. This is in addition to the WinHelp functionality. This help window is different in that it will take you to different parts of the documentation depending on which window you have in the foreground. The help file is the WAPRSdoc.htm HTML document. Built in is a simple HTML parser. The help file is not loaded until the first time you access it, then it is kept in memory.

The WAPRSdoc.htm file must be in a directory called "Docs" which must be in the same directory as WinAPRS.EXE

MAPS

The map file format for WinAPRS is EXACTLY the same as MacAPRS. This means that all of the maps developed for MacAPRS are usable for WinAPRS. You must have a "Maps" folder (directory) in the same folder as the MacAPRS / WinAPRS application. All Maps must be placed inside this folder. You can have folders inside of the map folder. These will be displayed as a hierarchical menus.

The maps that are used with DOS-APRS work just as well, simply put them into the same MAPS folder and they will show up in the MAP menu. There is no "MAPLIST.DAT" file as there is in DOS-APRS. All you have to do is put the maps in the MAPS directory and run the program. Please note that the DOS-APRS maps have far less resolution than the MacAPRS maps. They have a maximum of 3000 points. We have some MacAPRS maps that have 130,000 points and recently created one map that has 250,000 points (it took a few seconds to draw).

On Windows, if you put too many maps in the Maps folder, you can't see all of them in the menu. Go to the Map List window. You can double click on the map there and it will bring up a new window with that map.

Maps from the CD-ROM we produced must be copied from the CD-ROM to the MAPS directory before they can be used with WinAPRS.

Please note that if you put maps in the folder while MacAPRS / WinAPRS is running, you have to quit and restart before it will recognize the new maps.

NOTE: The ability to directly read DOS-APRS maps is new for MacAPRS as of Version 2.2.0.

You can hold down the option key (Mac) then click and drag the mouse, the area selected will become the new map zoom area. For Windows, use the right mouse button.

The format for the map file is explained in a separate document, please refer to Map File Format Documentation

Some of the maps for Macintosh on the TAPR FTP site are in Macintosh "sit.hqx" format. This is similar to ZIP format for PCs, but of course not compatible. We have found a PC program called SITEX10.EXE that allows decompression of these files on PCs. It can be found at:

Mac/WinAPRS Map CD-ROM We have a CD-ROM full of maps for use with Mac/WinAPRS, this CD-ROM contains over 600 megabytes of Maps. It contains maps of several different resolutions including very high detail street level maps for most of the major metropolitan areas.

The major areas of maps include

This CD-ROM is available for $25.00 plus $5.00 S/H from the same address as registration.

Click here to see the Map Outline areas. The red boxes indicate hi-res street level maps, the blue boxes indicate regional maps.

Map Windows

Both versions support many map windows open at the same time. On startup, one map window is opened and the first map in the map folder is used. To create additional maps, use the "NEW MAP WINDOW" command under the "Windows" menu. Then use the "MAP" menu to select which map to use. You can have as many maps open as you have memory to handle. When you run out of memory, you will get an warning and it won't open the map. You can also go to the map list window and double click on the name of a map file, it will bring up a new window with that map.

Map movement

In both versions, you can click on a location in the map and then cause it to zoom-in or zoom-out. Use page-up and page-down or the '+' and '-' keys. You can at anytime go back to the default magnification (Home View) by hitting the 'Home' key or the 'h' key. Once you have zoomed in on a map, you can use left, right, up, and down arrows to move around within the map. It does NOT automatically switch to another map when you reach the edge of the current map.

Map Boundaries

Display Map Boundaries command will show the outline of all of the maps on the current map window. This will show you the bounding rectangles of each of the maps. You can also do this by hitting the 'B' key.

A note when using dos maps. Many of the dos maps will not show up at first when you display the map boundaries, this is because the Mac/WinAPRS maps have a 256 byte header that has ALL of the information needed. The DOS maps have to be read entirely in before that is known. Some DOS maps have enough information in the first few lines so that this information can be displayed, many do not.When you open any dos Map (by selecting it from the Map Menu or double clicking from the map list), the boundary information is then saved for future reference.

Map Zooming

You can make MacAPRS / WinAPRS automatically bring up the next higher detail map by double clicking on a point. For MacAPRS, hold down the option key when double clicking. For WinAPRS, double click with the RIGHT mouse button.

List Windows

There are many different types of list windows in MacAPRS / WinAPRS. Each of the windows supplies a list of information organized in a different manner. Some of the information is constant such as the current list of maps. Most of the information is dynamic and will change as stations appear, etc. Message List: MacAPRS / WinAPRS recognizes standard APRS messages. This window shows all of the messages that have been seen since the program started. Messages TO you will be shown in RED. Messages FROM you will be shown in BLUE until they are ACKnowledged, then they will be shown in GREEN. Bulletins will be shown in DARK BLUE. Station ID's will be shown in light BLUE. Other messages will be shown in BLACK. Selecting a message and typing 'R' will REPLY to that message, already filling in the destination call sign. You can click on the column headers and the messages will then be sorted by that column.

Map List: The Map list is a list of all of the currently available maps: this is NOT to be confused with "MAPLIST.DAT" from DOS-APRS. This list shows the name of the map file, the name of the map, the number of points, the number of labels, the creator and the type (Mac/Win or DOS). For DOS-APRS maps, the number of points and the number of labels is NOT available unless you read the entire map in and count them. Therefore this information is not available in the beginning. As soon as you use a particular map, that information is updated in the map list window so the contents of the window will change. While talking to several of the beta testers of WinAPRS, I have mentioned the "Map List". This refers to THIS window, NOT the menu list.

You can double click or hit the return / enter key and a new map window with the selected map will be created. Remember, you can have as many maps open as you have memory to handle.

Station List: This window shows all of the stations seen since the program started. The list includes the ICON of the station, a second ICON if the station has reported more than one type, i.e. QTH and WEATHER, call sign, number of packets, and station ID if any. While in this window, you can Double Click on a station to bring up the Station Info Window for that station. You can also use the up-down arrow keys and then hit RETURN or ENTER to bring up a Station Info Window. Page-Up and Page-Down work also. Note: If the internal buffers overflow, the packet list will reset back to zero. Therefore, this window might say that you have received a large number of packets from a station and not show any. Don't let this alarm you.

When the message buffer is full, it will delete the FIRST HALF of the messages EXCEPT for any messages that are actually to you. It will continue to do this as every time the message buffer fills up. In other words, you can go away for the weekend (or a whole week) and come back and ALL of the messages that were sent to YOU will still be there, all of the recent messages will still be there. You don't lose anything important and you don't have to remember to clear the message list.

History List: The history list shows ALL of the packets received. This can get to be a very long list. When it fills up, it dumps the buffer and starts over.

Weather List: This window shows data from Weather stations and includes station type, call, time, temperature, rain fall, pressure, wind speed and direction, and weather alarms.

Flagged Station List: is a list of stations that you have "flagged". You can flag a station by going to the Station List window, selecting a station, and hitting the 'F' key. This allows you to keep track of stations that you are interested in without having to scroll through the entire list.

When List: Displays a window showing when the stations in the Station List were heard.

Tracked Station List: Shows the moving stations that are being tracked.

RDF List: Shows a list of stations reporting Radio Direction Finding information

Telemetry List: The APRS protocol defines an ability to have telemetry data transmitted from something like a balloon. This window will display that information if any is available.

Internal State: This window shows the values of important settings inside the program. This is different from the settings dialog boxes because they can be missleading at times. This window allows you to look at all of the important internals in one place and will allow us to better assist users in case of problems.

Memory Usage: For diagnostics mainly, to help determine when and where memory leaks are occurring, not very useful for general use.

Unproto Path: This window shows a list of all of the stations showing the path that was used for their data to get to you. This is useful in looking at which digis get used most and is the first step in supporting automatic path selection for responding back to other stations. Column 1 shows the station ID (call sign), station 2 is a "Y" if the station was heard direct, the rest of the columns are the digis, starting with the station callsign in the order they were seen. This window can be sorted by any column by clicking on the heading for that column. Stations that were heard direct are displayed in green.

Airport List: If you have the file "Airport.dat" or "Airport.data" in you DATA directory, then you can display most of the airports in the world. Select AIRPORTS under the DISPLAY menu, this will draw all of the air ports in the list on the current map. This is a temporary display only and the airports will disappear the next time the map is redrawn. If you hold down the option key for Mac or the Control key for Windows, it will display the airport 3 letter code as well.

You can look at the entire list by selecting AIRPORT LIST under the LISTS menu. This will display the entire list showing the airport code, city, lat / lon and elevation. The elevation data is not present for all of the airports but most of them. You can sort the list by clicking on any of the column headings. This can be interesting when you do a display airports because they will be displayed on the map in the same order they appear in the list. i.e. sort by elevation then do a display for the entire USA map.

If you double click on an airport in this list, you will be switched to the best map currently open that contains that airport and shown were on that map the airport is. If no map contains the airport, it will beep.

The airport data file can be found on the CD-ROM that we produced or on the FTP site, it must be placed in the DATA directory and MUST be named "AIRPORTS.DAT" for Windows and "AIRPORTS.DATA" for Mac.

Logging

There are several different logging options. All are turned on and off from the LOGGING menu.

Menu Commands

File Menu Edit Menu Settings Menu Logging Menu Map Menu Display Menu

Terminal Window

Under the "Windows" menu, select the terminal window command. This will bring up a terminal window that will allow you to talk directly to your TNC or other port. It will connect to whichever port you have open. If you do not have any port open, it will not let you open the terminal window. During the time that the terminal window is open, APRS data STILL gets processed. If the Terminal Window is the FRONT MOST WINDOW, then WinAPRS will NOT output any commands or strings to the TNC. If the terminal window is not the currently active window, then WinAPRS will output as normal. At ALL times, the INPUT from the port is still processed normally by WinAPRS so you do not lose any data.

Messages

APRS users can send one line messages to other APRS users. These messages are then acked from the other station. The messages can viewed in the MESSAGE LIST. Messages to you are red, messages from you start out blue and turn green when they are acked.

Bulletins and Announcements

Messages, Bulletins, and Announcements can be re-queued by CLEARING them in the MESSAGE window. They can also be canceled by deleting them

You CLEAR messages by selecting the message and hitting 'X' or '\' or the CLEAR key on a Macintosh.

To DELETE a message, select it and hit DELETE or BACKSPACE.

Refer to Key Board Short cuts page for all of the options in the message window.

APRS Objects

You can add an object by clicking anywhere on a map, then selecting the "edit/add object" command from the EDIT menu. Fill out the information. You can change the location by clicking on the object, then "edit/add object" it again, OR, you can hold down the Command/Alt key and drag it to the new location.

Creating: When you create an object, if you want it to be transmitted out so others see it, make sure that the OBJECT setting in the "Position Rate Settings" "Object reporting rate" dialog box is something other than 0 (the default) for the band you desire. A good recommended value is 30 minutes or higher. You also need to make the Object active by checking the "Object active" box and the "VHF" or "HF" box in the "edit/add object" dialog box.

Moving: To move an object on the screen, hold down the Command Key (Mac) / Alt Key (Windows) and click on the station, you can then drag it to a new location. If someone else moves the object your copy will become inactive and you will need to re-activate if you want to move it again and have it transmitted. To re-activate it you must click on the object once and the edit/add object from the edit menu again and set the HF/VHF and Active flags. The idea here is that only one station can really send the location of a given object at a time.

Removing: To delete an object, go to the station list window, then select the object to be deleted and hit the delete key or backspace key(Windows).

Additional notes: The objects are uniquely identified by the Callsign field in the edit/add object menu. If you use the same callsign name to try to create a new object you will not get a warning. The old object will be deleted and the new one will appear. This is useful if you need to relocate an object since you do not need to delete the old one.

Fancy symbols for objects can be selected in the edit/add objects menu STATION TYPE field. To view the possable symbols use the LIST -> SYMBOLS LIST function or just type random charaters in this field till you find something you like. (- minus sign is a home QTH).

HSP Support

HSP (Hardware Single Port) was designed to solve the problem of only having one serial port and the need for both TNC and GPS input. This is done with a special cable that has a simple transistor switching circuit. The DTR (Data Terminal Ready) line from the computer is used to switch this circuit allow for input from two different devices. It only switches the data into the computer, not out of the computer.

HSP is supported on the VHF TNC input and the HF TNC ports only. To enable this, go to the Serial Port dialog box and set the appropriate check box. HSP is turned on (switched) for 4 seconds of each minute. This has been tested with the PacComm HSP cable.

Please note that the PacComm HSP cable needs +5v on Pin 6, the Handi-packet does not provide this. You might need to install a jumper between pin 6 and pin 8 of the DB9 on the TNC. Please refer to the schematics or customer support of your TNC manufacturer.

HSP does NOT support weather input.

The Mac version does not support HSP and is not likely to. To get around this problem use a TNC with a GPS input such as the Paccomm Pico-Packet. Also the MPA (Multiple Port Adapter) from Agrelo can be used.

Audio Alarms (sound files)

When various events happen, audio alarms are played to announce that fact. These alarms can be turned off under settings. For MacAPRS, these sounds are stored as 'SND ' resources within the file, for WinAPRS, they are external .WAV files. These files MUST be in a directory called SOUNDS which MUST be in the same directory as WinAPRS.exe

Mouse Down short cuts

These "modifiers" to affect the operation of mouse down, mainly in the map window. By holding down the specified key, you can invoke many other functions. For most of these operations, the key must be held down the entire time.

MAP Window

List Windows

Function Key Shortcuts

Keyboard short cuts

MAP Window

List Windows

Station List Window

Message List Window

Printing

On the Mac you can print any and all windows. The print command applies to the current window. The map windows will be resized to fit the paper of the currently selected printer so they should never take up more than one page on the output. Also the print code has been written so that it works well with pen plotters and will take proper advantage of the large print area of a large pen plotter.

WinAPRS can print the list windows, map windows do not print at this time.

FIND

Find can be a VERY useful tool, with it you can find the location of a zip code, of an airport, of an existing station or of any ham listed in a call book data base.

In the map window you can search for these items

In the station lists you can search for call signs, in the airport list you can search for a city name, in the history list you can search for any text.

Map Display Options

Under the DISPLAY menu is the Map Display Options. This allows you to set many options for how maps display including: These options can be applied to the current map, all maps, or set as default.

CD-ROM call sign data base support

MacAPRS / WinAPRS can take advantage of call sign databases on CD-ROM. Under settings menu, select CALLBOOK, there is a pop-up menu to select which CD-ROM data base you want to use. When selected, this automatically fills in the paths for the files. If you have copied items to your hard disk you can manually change these paths. For Windows, you must set the drive letter for your CD-ROM drive.

The following CD-ROMs are supported:

Some of the CD-ROMs have to have an index created in order to use them. To create the database, go to the CALLBOOK DATABASE under SETTINGS menu. Select the desired database from the popup menu, at the bottom of the dialog box is a button that says MAKE: CallSign index. Select this button and it will create the index.

PLEASE NOTE: This can take a while and generates an index that is typically 3 megabytes. For WinAPRS this cannot be aborted, for MacAPRS, Command-Period will abort it. For WinAPRS with a 4X CD-ROM drive on a 100 megahertz Pentium it took about 4 minutes each to create the QRZ and SAMS index files.

Each time you get a new CD-ROM, simply throw away the old index file and re-create it. You do not have to download it off of the internet. The index files are compatible between Mac and Windows, so if you create the database on one machine, you can copy it to another of the other type.

The index file is automatically created in the DATA folder inside of your WinAPRS folder. For the Buckmaster CD-ROM, the index is already on the CD-ROM and is left there. Below is a table for which data bases need indexes

Callbook Database Indexes
CD-ROM Index required MacAPRS WinAPRS comment
Buckmaster No N/A N/A Included on CD-ROM
QRZ Yes Tested Tested About 3.8 meg
SAMS Yes Tested Tested About 3.8 meg
AMSOFT No N/A N/A -
PERCON No N/A N/A -
FCC Database Yes Tested No -

UNPROTO path

Probably the biggest single confusion about APRS is the UNPROTO path. This is the path that the TNC is set to use for unconnected packets. (All APRS communications is via unconnected packets known as UI frames). There is a window that shows the paths that each station uses (under LIST WINDOWS). This can be very helpful to see what others in your area are using.

There are several guidelines when setting your unproto path.

  1. NEVER use 3 of the same thing such as WIDE,WIDE,WIDE. This will cause TREMENDOUS amounts of excess retransmission of packets. In some cases enough to cripple a network.

  2. Including a "GATE" in your path will allow your packets to GATEWAY from VHF to HF or vise-versa. Do NOT put more than one GATE in your path.

  3. RELAY should be used if you are new station, but after you figure out which path to use, then discontinue using RELAY at all.

  4. RELAY should NEVER be anywhere EXCEPT the first item in the proto path.

  5. NEVER use RELAY after a WIDE.

  6. In a given area, there should not be more than 2 digis with an alias of RELAY. More than that can cause a given packet for a new user or mobile user to be repeated 27 times. If you can hear 2 digis with an alias of RELAY, DO NOT set yours to RELAY.

  7. In a given area, there should not be more than 2 digis with an alias of WIDE, if you can hear more than one WIDE, DON'T set your alias to WIDE.

  8. RELAY,WIDE,WIDE should NEVER be used by a home station, however it is a good choice for a MOBILE station.

Discussion on unproto paths

This section is meant to familiarize you with the concepts of APRS operations so that you can get running with maximum efficiency and minimum disruption to other stations in the network. The information in this sections applies to all versions of APRS.

Since APRS stations do not "connect" to each other as in a typical packet QSO, but rely on "unconnected" packets, the only way to get your data to others beyond your station's reach is through the use of digipeaters. Users of APRS have standardized on a scheme for digipeating that requires some explanation.

Just as it is advantageous to have a packet node or a repeater located in a high spot with great coverage, so it is with digipeaters. In APRS terminology, such a wide-coverage digi is called a WIDE. In any given area, there should only be one WIDE, and that station should be able to work the adjacent WIDEs and should operate 24 hours a day. Don't be an "ego-WIDE"; that is, setting yourself up as a WIDE when you cannot provide the functionality of a true wide or are in an area already served by a proper WIDE. You will only cause problems on the network and earn the wrath of those whose traffic you are affecting.

Of course, we cannot expect every station in a given area (mobiles especially) to be able to work a WIDE (especially if they are on the move), so to assist those stations to make a WIDE, there are RELAY stations. A RELAY station can be any station that can work one or more WIDEs reliably. There should be only one RELAY in a given area that can work a given WIDE; the same "ego-WIDE" caution applies here. Of course, if two (or more) stations overlap in coverage slightly but primarily cover differing areas, the benefits of covering the extra area might outweigh the extra traffic and collisions on frequency. This is where those Ham "experimenter" skills come into play. Remember, when all is said and done, we're here to innovate and experiment while (hopefully) having fun. Don't get too obsessive or relaxed with any of the guidelines herein.

So now, as a user, needing to choose a path to digi your packets through, what should you use? Initially, set your UNPROTO path to RELAY (see your program docs for info on how to do this). Once you see some stations appear on your map, see who you can hear directly using the DIGI or PROTOPATH list. Can you hear a WIDE directly? If so, change your UNPROTO path to WIDE (or WIDE,WIDE if you want to go two hops). If not, and you can work a RELAY directly, try RELAY,WIDE (or RELAY,WIDE,WIDE).

You may also see a GATE station. GATEs pass traffic from HF nets to VHF nets. GATEs should never be used from VHF to HF - this will have real bad implications for the HF net (perhaps even crippling the entire net). The 300 baud traffic of HF should pose no problem on the VHF 1200 baud net, but the reverse is certainly not true.

DIGI PATH DO'S AND DON'TS:

Alternate Paths for VHF and HF

As explained in the section above, you have a PATH setting for unconnected packets. This path is normally something like "APRSW via RELAY,WIDE". This path is set in the TNC settings dialog box in unser the SETTINGS menu. In order to change the path, the TNC has to be taken out of CONVERSE mode, sent the new command, then put back in CONVERSE mode. This is why the changing of paths was not implemented in earlier versions. When you make a change, it stays in affect till you change it back. If you close the TNC port and reopen, or restart WinAPRS, it will go back to the value in the TNC settings dialog box.

To use this function, you need a file called "ALTPATHS.TXT", this is a simple text file as follows 

	relay,wide
	wide,wide
	wide,gate
On starup, WinAPRS reads this file and creates 2 sub-menus under SETTINGS, one for VHF and one for the HF port. There is also an "OTHER" option that allows you to type in a path. The "APRSW VIA" is inserted automatically.

You can add as many options to this text file as you need to.

Setting up a Gateway

It is possible to set up a station that has radios on both VHF and HF and have it "gate" packets between the two. Packets with "GATE" in their path will then be passed on to the other band.

The purpose of a HF to VHF gateways is to permit VHF local area APRS nets to see mobile stations on HF nets.

VHF stations in general should NOT gate onto HF, but HF stations should gate onto VHF, this is because of the slower bandwidth of HF. Of course in some situations, gating onto HF may be important.

Several TNCs such as the AEA DSP-2232 and the KAM Plus have this ability built into the TNC.

A gateway gates both directions, if someone on VHF has GATE in their path, your station will GATE them to HF, if someone on HF has GATE in their path, your station will GATE them to VHF. If you set your station up as a gateway you are on BOTH HF and VHF, YOU do not need to have GATE in your path at all.

Overlay Files

There are many times when you need a graphical display of a large number of stationary objects. These would be items that are too numerious to transmit and are intended for local references. Examples are list of digi-peaters, list of repeaters, list of airplane crash sites for Search And Rescue. Mac/WinAPRS supports POS files. This is the same format as dos *.POS files. To use them goto FILE menu OPEN command. Select any file with a a POS extension. This loads the file into memory, then type "O" for Overlay on any map window and the entire list of items will be displayed.

You can create an OVERLAYS folder and place all overlay files in this directory. The items will be added to a pop-up menu in the DISPLAY menu for quick access to all of the files that you have in this folder.

TCP/IP Connections

There are several versions of APRS servers (reflectors) on the internet, these system listen to a TNC and re-brodcast the information from the TNC to anyone who has connected in via TELENET protocol. This allows people to see APRS information from other parts of the country. Steve Dimse has written APRSserve which is the most sophisticated of these servers.

To connect to these servers, you have to be connected to the internet, either directly or via dialup (PPP or SLIP). Also you must have a file called "APRSserv.txt", this contains the names and port numbers for the various APRS reflectors. Of course you MUST also have TCP/IP installed and configured. If you have internet access and can run Netscape or other Web browser, then this part is already done.

To open the connection, simply select the server you want to connect to from the TCP/IP connections sub menu under SETTINGS menu. Then sit back and watch, stations counts greater than 700 is common.

Weather Options

There are several features of Mac/WinAPRS boundaries tailored to weather watching, these include:

Weather Station Input

MacAPRS and WinAPRS support several weather stations. Currently supported units are:
  1. MANUAL
  2. Peet Bros Ultimeter-II
  3. Peet Bros U-2000
  4. Peet Bros 500
  5. Heathkit 5001
  6. Davis
  7. As soon as we can get one of the new Radio Shack units, we are going to try to support it as well.
When weather data comes in from any of the supported units it is stored internally and available for local display. You can display the last 24 hours in the "24 Hour Weather Chart". The current data is then available to output over the air either manually (by selecting the TRANSMIT WEATHER menu) or automatically form the weather options dialog box.

In order for Mac/WinAPRS to transmit the weather, the data MUST be less than 90 minutes old. For manual stations, this means that you have to have set it from the dialog box within the last 90 minutes. For automatic input, a valid packet must have come in within the last 90 minutes. I know, if it's a weather station connected to your computer it's always coming in, well not quite. I had a case where the cable from the weather station got knocked out and I didn't notice it. A day went by before I realized it and for that entire 24 hours I was transmitting the same temperature as if it was current. By making all weather input to be required to be not less than 90 minutes old, it assures other stations that if they see data from Mac/WinAPRS, it IS current. For those situations where more up-to-date weather data is required, the weather display mode (described below) shows you how old the actual data is.

The Ultimeter II and U-2000 are available from :

The weather station display looks like this:

National Weather Service Watches and Warnings

APRS has become a very good tool for weather reporting to the National Weather Service, The NWS office in Mt Holly, NJ in particular requested the ability to use APRS to help get the word out to Skywarn personel about activations, watches, and warnings. These are almost always done on a county-by-county basis. A feature was added to Mac/WinAPRS to display which counties have Skywarn activation, Watches, or Warnings activated.. For this to work, you must have a folder named COUNTIES and it must contain some special map files. These map files are supplied by us for the ENTIRE United States. Each map file is an outline of exactly one county. For example, NJ_MIDDLESEX.MAP is a map file for the county that I live in, Middlesex County, NJ. You can place files in folders inside of the COUNTIES folder, for example, inside of COUNTIES, I have NJ, MD, and PA folders, inside of them are the county files. This makes it easier to keep track of if you have lots of county files.

Operation

Mac/WinAPRS can initiate a message sent to NWS-SKYWN, and listing the counties that are activated, any station that has list of counties in the COUNTIES directory will then show that county hi-lighted on the maps. Yellow means Skywarn activation, orange means Watch and red means Warning. All activations, warnings and watches have an expiration time on them. The color hi-lighting of the counties will automatically disappear when that time has passed. The transmitting station can also deactivate a county which will cancel the current status immediately.

Since the National Weather Service always issues weather bullitens in LOCAL time, these warnings are based on LOCAL time. It is therefore important that you have your clock set correctly to local time and the UTC offset set to make the ZULU time work properly.

Backwards compatible

Please note that this is NOT a change in the protocol, simply a message adressed to a specifc address similar to bullitins. Older versions and DOS versions will be able to review these messages in the message list

Sending warnings etc

The ability to initiate any of these levels of activation is going to be restricted to the NWS office and trained Skywarn personel, the main reason for this restriction is that the method for sending them out has been made so easy, that we do not want people to do it by accident. If you want the ability to initiate these messages, please contact the authors (Mark Sproul) sproul@ap.org, for New Jersey you can also conact Paul J. Toth - KB2WNZ KB2WNZ@amsat.org Paul covers all of the areas handled by the Mt Holly, NJ office and the Brookhaven, NY office. The intent will be that anyone who is active in Skywarn and therefore a trained Skywarn operator can have this ability to transmit these warnings, but we do not want hundereds of users sending out warning activations by accident or just to see what it does.

List of APRS contacts for NWS wanrings in different areas

Weather Display Options


You can display weather data along side of the station ICON on the map for all stations that report weather information. The data format and amount of data displayed can be customized in the Station Display Options dialog box. At present, not all of these features are fully implemented but are displayed here to give you an idea of what's to come.

CALL 1 through CALL 4 are the LOCATIONS you want the CALL SIGN displayed. You can disable the call sign all together if you like.

Age is the age of the last report. This allows you to keep track on the screen the time of the last report. In the case of severe weather, a report that is 10 minutes old may not be of much use and misleading.

Error is not yet fully defined.

Winds Aloft

MacAPRS / WinAPRS fully supports the APRS weather protocols. In addition they support much more sophisticated weather display and more will be added in the future.

The first advanced weather feature is the Winds Aloft display.

In order to take advantage of this feature you must have several things.

Once you have the files, go to the select OPEN WEATHER from the FILE menu, and open each of these two files, not much will happen but then redraw the map and you will see the display shown below.

To display the different altitudes, press the keys 0 through 9, each one will display a different elevation starting at 3000 feet. Note that some locations, such as Denver Colorado will not show any wind at that altitude because Denver is higher than 3000 feet. Also, control-W will display ALL of the winds at the same time.

Note that these airports will now show up in the station list. They aren't really stations but that is the way they are represented internally. You can turn on and off the display of the airport names by changing the Display Callsign option under the display menu.

Global Labels

Global Labels allows you to create a set of map labels that get drawn on ALL maps, these labels are specified by a lat/lon position and a range. If the position is on the map, and the range is correct, the label gets drawn. Create a folder (directory) called LABELS in the same directory as the application. You can put as many text files containing labels here as you like. These labels will be shown on ALL maps. This allows you to create a list of your own labels that get added to ALL maps. The format for the file is EXACTLY the same as the label entries in a DOS-APRS map file so you can use a text editor to copy any and all labels that you want. There is no limit to the number of labels that you can have in this file (well, it will probably break if you put more than 32,000 labels in it). The label range feature is implemented so that you can set the labels so they won't clutter up the map if you are zoomed out.

The format for the label is Label,latitude,longitude,range There are 3 different variations of the format

All lines starting with "*" are comment lines and igored. In the future you will be able to edit these labels from within MacAPRS / WinAPRS.

Vectors

In the same files as the global labels, you can create global vectors. These would be used to trace the route of a bike race, or to mark of a grid for a special event etc. The vectors are listed in normal Lat/Lon pairs with a "/" in the first column. A "\" in the first column means start a new line (i.e. pick up the pen). Here is a sample These vectors will be displayed on all maps at all resolutions, to turn them off, remove them from the labels folder and restart. It is perfectly OK to mix global labels and vectors in the same file. This allows you to create a single file for a paticular event that you only use once a year. During the rest of the year, simply move the file to some other directory.

GPS/NMEA data

You can also place raw GPS data streams in the labels folder, they will behave the same as the vectors above. This allows you to drive around a bike race cource logging the GPS data, then simply throw that file into the LABELS folder and have an automatic overlay in red of the race course.

Window Config Files

You can save your set of windows including the location of the windows. Win/MacAPRS will automatically load WinAPRS.cfg / MacAPRS.cfg on startup if present. At anytime you can load another config file by simply doing a FILE OPEN. When you do this it will close all existing windows and open up all of the news ones in the specificed config file. To save a config file, open up the window(s) (map or list or other) and place them on the screen as desired. Then do a FILE / SAVE WINDOW CONFIG.

RDF - Radio Direction Finding

Radio Direction Finding, also known as fox hunting, is the use of radio equipment to find the direction of an RF source. With this information obtained from more than one location, triangulation is possible. WinAPRS supports the use of the DF-Jr made by Agrelo Engineering.

WinAPRS supports two modes of RDF operation, local and remote, these refer to the location of the RDF unit. In local operation, the RDF unit is connected directly to your computer. This can be done from a perminate (non-moving) station or from a mobile station.

Local RDF Operations - stationary

For operations where the RDF unit is connected directly to the computer, every RDF report is directly displayed on the screen. In this mode, the RDF reports are not automatically sent out over the air. The default settings for the DFjr are all that are needed.

Local RDF Operations - mobile

If you are operating an RDF unit from your car while moving, you must have a GPS unit as well. The GPS unit must be configured to output NMEA data (all current models that have data output have NMEA as an option). This data must be feed into the the MPA (Multiple Port Adapter) from Agrelo. The DFjr will then periodically send a GPS string to the computer in addition to the RDF data. This allows you to use both inputs to the computer on a single serial port. This is important since many lap tops only have one port. Additionally, a TNC can be connected to the MPA as well. To enable this feature on the DFjr, use menu option 3, submenu 1. To enable this, press MENU 3 times, make sure sub-menu #1 is selected (the LED at the 11 o'clock position) and press enter.

Remote RDF Operations

In remote operation, the DFjr is listening to one radio and transmitting the direction/strength information out the APRS frequency via a TNC and a SECOND radio. Anyone monitoring this output frequency with APRS will then see the vectors. If you have 2 or more of these units located in different places and both listening to the same frequency. Each time a transmitter is keyed on that frequency, you should get 2 vectors giving you fairly accurate location as to the where the transmitter is.

Set up of a remote DF station is straight forward but requires some complexity. First there are several paramters in the TNC that have to be set for proper remote RDF operation

The TNC is to be programmed to have a beacon text as follows

BTEXT !hhmm.ddN/hhhmm.ddW\Comment as you like 

	ddmm.dd
	hh	=	Degrees
	mm	=	minutes
	.dd	=	100ths of a minute
You set the BEACON RATE with the BEACON EVERY command.. This is normally set to something long, for example, a value of 30 will cause it to send out the location every 5 minutes. Most operations should set this to 30 minutes, 180 would be the proper value for 30 minutes.

BE E 30

You program the TNC to automatically come up in CONVERSE mode. Check the TNC manual for this.. Both the Paccomm Picopacket and the Kantronics KPC-3 have this mode. The command for Paccomm is UIMODE ON.

You set the DFjr to only output data when the QUALITY gets above a reasomable number, probably at least 4, but that has to be experimented with..

Then, anytime the TNC receives data from the DFjr, it is of the preset quality and gets transmitted immediately.

Below is an example of data that would be received over the air: 

KB2ICI-1>BEACON:!4020.00N/10020.00W\
KB2ICI-1>APRS:%020/5
KB2ICI-1>APRS:%022/6
KB2ICI-1>APRS:%024/5

KB2ICI-2>BEACON:!4040.00N/10040.00W\
KB2ICI-2>APRS:%098/5
KB2ICI-2>APRS:%100/6
KB2ICI-2>APRS:%102/5
NOTE: Each of the different TNCs used must have a different call sign (ID).

Each time data is received from the remote site, the data is displayed on the screen as a colored vector showing the bearing vector.

Mobile operation WITHOUT a computer
A remote station could be setup WITHOUT a computer exactly the same as above with the addition of a GPS input. This is not a very common setup but could be done if another moving DF unit was required and a lap top was not available. The GPS would be connected to the MPA unit and the GPS option in the DFjr (Menu #3) would have to be enabled.
Hints

APRS uses

Known limitations

As with any software package there are limitations. This is a list of specific issues that you may encounter.

SOFTWARE ARCHITECTURE

MacAPRS and WinAPRS are written in C and C++. They do NOT use the Microsoft Foundation Class (MFC) or any other C++ framework. They are written using a framework that I wrote for cross platform software. This architecture started out as normal C as far back as 1990 and in February of 1997 started migrating to C++. Much of the code is still written in C and much of it is in C++.

MacAPRS and WinAPRS are ONE set of source code written to work on both platforms and evetually X-Windows (Linux). The only part of the code that is not the same is the serial I/O drivers and the main event loop. ALL remaining portions of the code are one unified set of source code.

MacAPRS and WinAPRS are both written and compiled using CodeWarrior from Metowerks. CodeWarrior is a full featured development environment that is available for both Mac and Windows. It allows compiling for Mac AND Windows on either platform. It does NOT convert software to run on another platform, just acts as a cross-compiller/debugger.

Serial Port problems

During the beta testing of WinAPRS, the most common problem had to do with serial ports. This seems to be a standard problem on PCs. I have done everything I can to write to the proper Windows guidelines to make the serial ports work as cleanly as possible. If you are having problems, try this.

When the start-up dialog box is displayed, hold the SHIFT key down while clicking the OK button. This will turn on serial port debugging messages. This may help in solving serial port problems.

Trouble Shooting

Here are some hints for common problems.

Other APRS Information on the web

Related information

INDEX

NOTE: All manuals should have indexes, using the Web for documentation makes indexes much harder. Please note that this index is intended for the PRINTED version may often be off by a page or more. I realize that this may be a minor inconvenience, but I think it is better than no index at all.

This index was setup with the document printed by Netscape with the following settings. 

	FONTS
		Proportional	Times size =12
		Fixed		Courier Size = 10
	Page Setup
		both header (title) and footer (page numbers) are turned on


Back to APRS home page
This documentation is © 1996-97 by Mark and Keith Sproul.
APRS™ © Bob Bruninga (WB4APR)
MacAPRS™, WinAPRS™ © by Mark Sproul (KB2ICI) and Keith Sproul (WU2Z).

Access counter